# Other issue

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# What should I do if the device becomes excessively hot?

## Confirm whether the temperature is actually too high

Run the following command to obtain the current device temperature:

```bash
qpi-config dump temperature
```

If the temperature exceeds 80 °C, take cooling measures immediately.

## Identify the heat source

Check CPU utilization and frequency:

```bash
# Check CPU utilization.
top -b -n 1 | head -20

# Check the operating frequency of each CPU core to determine whether it remains at the maximum frequency.
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq

# Check whether the performance governor is enabled.
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
```

Check GPU utilization:

```bash
cat /sys/class/kgsl/kgsl-3d0/gpu_busy_percentage 2>/dev/null
cat /sys/class/kgsl/kgsl-3d0/max_gpuclk 2>/dev/null
```

Check storage utilization:

```bash
iostat -x 1 3   # Display %util.
```

## Software cooling measures

Reduce the maximum CPU frequency:

```bash
# Display available frequencies.
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies

# Set the maximum frequency, for example, to 1.6 GHz.
echo 1651200 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq
```

Switch the CPU governor to `schedutil`:

```bash
echo schedutil > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
```

Reduce the maximum GPU frequency:

```bash
# Display available frequencies.
cat /sys/class/kgsl/kgsl-3d0/devfreq/available_frequencies

# Set the maximum frequency, for example, to 550 MHz.
echo 550000000 > /sys/class/kgsl/kgsl-3d0/devfreq/max_freq
```

Check for processes with abnormal CPU usage:

```bash
ps aux --sort=-%cpu | head -10
```

## Physical cooling measures

- Place the development board in a well-ventilated environment.

- Install an active cooling module. The fan should increase its speed automatically when the device temperature exceeds the configured threshold.

# What should I do if a library does not work correctly?

## Identify and classify the issue

- Link error: The compiler reports *cannot find -lxxx*, or the error *cannot open shared object file* occurs at runtime.

- Runtime crash: The application reports *undefined symbol: xxx* or triggers a *Segmentation fault*.

- Functional error: The library loads successfully, but a specific API does not respond or returns an unexpected error code.

## Check whether the library file exists and verify the library search path

```bash
# 1. Locate the library.
find /usr/lib /usr/local/lib /lib -name "libxxx.so*"

# 2. Check whether the dynamic linker recognizes the library.
ldconfig -p | grep libxxx

# 3. Check whether LD_LIBRARY_PATH contains the directory.
echo $LD_LIBRARY_PATH
```

If the library is in a nonstandard directory, set *LD_LIBRARY_PATH*, or add the directory to a configuration file under */etc/ld.so.conf.d/* and run **ldconfig** to update the cache.

## Check dependencies to resolve undefined symbols

```bash
# List the library dependencies (safer than ldd because it does not execute code).
readelf -d /path/to/libxxx.so | grep NEEDED

# Check whether a symbol is defined in the library.
nm -D /path/to/libxxx.so | grep "  T " | grep symbol_name

# Alternatively:
readelf -s /path/to/libxxx.so | grep symbol_name
```

An undefined symbol usually indicates a library version mismatch or a missing dependency. If the symbol exists but the application still reports an error, the cause may be link order or ABI incompatibility.

## Check library version and ABI compatibility

```bash
# Display the embedded library version string.
strings /path/to/libxxx.so | grep -i version

# Display the library SONAME.
readelf -d /path/to/libxxx.so | grep SONAME
```

If the application was linked against libxxx.so.1 but only libxxx.so.2 is installed, an ABI change may cause a runtime crash even if the required symbol exists. A symbolic link, such as ln -s libxxx.so.2 libxxx.so.1, can be used as a temporary workaround. For a long-term solution, rebuild the application or install a compatible library version.

## Trace dynamic loading at runtime

```bash
# 1. Display the libraries loaded by the dynamic linker.
LD_DEBUG=libs ./your_app 2>&1 | grep libxxx

# 2. Trace attempts to open library files.
strace -e openat,open ./your_app 2>&1 | grep libxxx

# 3. If the application crashes immediately, inspect it with gdb.
gdb ./your_app
(gdb) run
(gdb) bt   # Display the call stack after the crash.
```

# How can I update a third-party driver?

1. Obtain the official SDK. See [Image Build](<../../Operating System/Yocto Linux/Image Build/Image Build.md>) for download instructions.

2. Add the third-party driver source code under *sources/quectel-src/kernel*.

3. Add the device tree node for the peripheral to *sources/quectel-src/kernel/qcom-6.6/arch/arm64/boot/dts/qcom/qcs6490-idp-pi.dts*.

4. Build and flash the image, and then verify the driver.

# What should I do if system performance is poor?

Poor performance is usually caused by a combination of CPU scheduling, memory pressure, storage I/O, thermal throttling, and software configuration.

## Identify the bottleneck

```bash
# 1. Display the 1-, 5-, and 15-minute load averages.
uptime
# A sustained load average greater than the number of CPU cores indicates CPU pressure.

# 2. Display per-core CPU utilization by category (user, system, soft interrupt, and idle).
mpstat -P ALL 1 3

# 3. Display memory and swap usage.
free -h
# Less than 10% available memory with nonzero swap usage indicates memory pressure.

# 4. Check storage I/O. A %util value near 100% indicates a storage bottleneck.
iostat -x 1 3

# 5. Check temperature and CPU frequency for thermal throttling.
qpi-config dump temperature
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq
```

Interpret the key metrics as follows:

- High `%us`: CPU-intensive user-space workload.

- High `%sy`: Excessive system call or driver overhead.

- High `%wa`: Storage I/O bottleneck.

- High `%si`: Excessive software interrupts.

- Temperature above 80 °C: Potential thermal throttling.

- Very little `available` memory in **free -h**: Memory pressure.

## Apply targeted optimization

### CPU bottleneck (%us or %sy consistently above 60%)

- Identify the processes with the highest CPU utilization.

- Reduce the load generated by cameras and other peripherals.

- Increase the real-time priority of critical threads, for example, by adjusting the scheduling policy.

### Memory bottleneck (very low available memory and nonzero swap usage)

- Identify the ten processes with the highest memory usage.

- Remove unnecessary log files.

- Check for DMA-BUF or ION memory leaks.

### Storage I/O bottleneck (%util in iostat close to 100%)

- Identify the processes generating the most write I/O.

- Reduce unnecessary log writes.

- Check for processes that write files too frequently.

### Thermal throttling (frequency reduction caused by high temperature)

- Confirm whether the system has triggered frequency throttling.

- Apply active physical or software cooling measures.

# How can I configure a service to start at boot?

`systemd` is the standard init system used by most mainstream Linux distributions, including Yocto-based systems. It provides dependency management, automatic restart, and environment variable configuration.

## Create a service unit file

Create a `.service` file under */etc/systemd/system/*, for example, *my-camera.service*:

```
[Unit]
Description=My Camera Service
After=network.target   # Start after the network is available.

[Service]
Type=simple            # Other types include forking and oneshot.
ExecStart=/usr/bin/my_script.sh
Restart=on-failure     # Restart automatically after a failure.
User=root              # Run as root.
WorkingDirectory=/opt/my_app

[Install]
WantedBy=multi-user.target   # Start when the system enters multi-user mode.
```

## Enable and start the service

```bash
# Reload the systemd configuration.
sudo systemctl daemon-reload

# Enable the service at boot.
sudo systemctl enable my-camera.service

# Start the service immediately, if required.
sudo systemctl start my-camera.service

# Display the service status.
sudo systemctl status my-camera.service
```

# How can I install a third-party driver?

1. Obtain the driver module: Obtain the third-party driver source code and cross-compile it in an environment that matches the development board's kernel version to generate a .ko module.

2. Transfer the driver module: Transfer the compiled .ko file to the development board through scp, adb, or a USB flash drive.

3. Load and unload the driver:

Load the driver with **insmod**:

```bash
insmod your_driver.ko
```

Unload the driver with **rmmod**:

```bash
rmmod your_driver
```

Run **lsmod** to list all loaded modules:

```
lsmod
```

# What should I do if no solution is available?

1. Visit the [Quectel FAQ page](<https://www.quectel.com/faqs-technical/>).

2. Ask a question on the [Quectel Developer Forum](<https://forumschinese.quectel.com/>).